If your application does not take advantage of the Macintosh’s color capabilities (as determined when initializing Tools Plus by way of the InitToolsPlus function), you can skip this section. This chapter deals entirely with drawing in color, as well as with the implications of making your application compatible with Macintoshes that have multiple monitors. You should already be familiar with Inside Macintosh Vol. 5 to understand the concepts behind color drawing and Color QuickDraw.
If you are using the simplest form of color drawing, that is drawing either objects or text using fixed colors and letting Color QuickDraw resolve all color discrepancies between monitors (or different settings on the same monitor), you don’t have to read this section. Also, if your application is merely testing for the presence or absence of Color QuickDraw, you can just use the HasColorQuickDraw routine.
You should read this section if your application will behave differently depending on the number of available colors or grays, such as displaying a color, gray-scale, or monochrome picture.
Within this section, all references to the term “color” also include “gray-scale,” or shades of gray unless otherwise stated. The term “color” does not include “black and white” such as the original 9 inch monochrome Macintosh monitors.
Using One Monitor
`````````````````
The majority of Macintoshes have only a single monitor, but even with a single monitor, your application may choose to behave differently depending on whether the user has set the monitor to 1-bit (black and white), 2-bits (4 colors), 4-bits (16 colors), 8-bits (256 colors), 16-bits (thousands of colors) or 24-bits (millions of colors), or to gray-scale of equivalent depth. Realize that the user can change a monitor’s settings at any time via the Macintosh’s Control Panels.
Never assume that the user has a specific monitor, or that the monitor is set to a specified number of colors. Before drawing or refreshing a window’s contents, your application should determine the monitor’s depth in pixels (by using the ScreenDepth routine), and possibly if the monitor is set to colors or gray-scale (by using the ScreenHasColors routine), then draw accordingly.
Using Multiple Monitors
```````````````````````
With Tools Plus, you can make your application “multi-monitor capable” almost as simply as making it respond appropriately to the number of colors available on the main monitor. This is accomplished by drawing the color-dependent contents of a window once for each monitor the window intersects. If the window is entirely on one monitor, its contents are drawn only once. If it intersects two monitors, its contents are drawn once for the first monitor and a second time for the second monitor. The portions of the window that are color-independent (i.e. they are drawn the same no matter what the monitor’s color capabilities are), need to be drawn only once.
Logical Screens
```````````````
Fortunately, Tools Plus has several routines that make the task of drawing a window’s contents on multiple monitors an uncomplicated process, that is by drawing on logical screens instead of physical monitors. A logical screen is the combined area of all available monitors that have the same [1] screen depth (number of colors) and [2] setting of “colors” or “grays.”
If your application is running on a Macintosh with three monitors, each being set to 256 colors, NumberOfScreens will report 1 logical screen, that being the sum of all three monitors. Your application can then update all three monitors simultaneously. Conversely, if two of those monitors are set to 256 colors and the third one is set to black and white, NumberOfScreens will report 2 logical screens. Your application can then update the pair of 256 color monitors simultaneously (1st logical screen) then the black and white monitor (2nd logical screen). Note that NumberOfScreens differentiates between color and gray-scale monitors, even if they are set to the same pixel depth.
The following example illustrates a typical application’s source code used to refresh a window. It accounts for multiple monitors, and for objects that are color-dependent (they are drawn differently depending on the monitor’s settings), as well as color-independent (drawn identically, regardless of the monitor’s settings).
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
{ the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the window }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
Note that this programmatic style is only a recommendation. You may decide to have self-contained color-dependent routines accessed from within sections of color-independent code.
BeginUpdate is a Macintosh Toolbox routine that sets the specified window’s visible region to be the same as the update region. This limits drawing to the region of the window that needs updating (refreshing). Call BeginUpdate and EndUpdate only if you are responding to a doRefresh event.
The NumberOfScreens function reports the number of logical screens (not monitors) that use unique color settings.
Call BeginUpdateScreen just before you begin drawing a window’s color-dependent contents. BeginUpdateScreen temporarily saves a copy of the current window’s visible region (visRgn), and replaces it with an intersection of the window’s visible region and the specified logical screen. This limits drawing to the area of the window that is visible only on the specified logical screen. You can use the ScreenDepth and ScreenHasColors functions to determine the color characteristics of the specified logical screen.
Call EndUpdateScreen after you have completed drawing a window’s color-dependent contents. It restores the window’s visible region (visRgn) to its original value, that being prior to being altered by BeginUpdateScreen. Your application should call the toolbox’s BeginUpdate and EndUpdate only if it is responding to a doRefresh event.
If you want to optimize the drawing of color-dependent windows, your application may want to check the current window’s visRgn after calling BeginUpdateScreen. If the visRgn is empty, it means the window does not intersect the specified logical screen, and therefore does not need updating.
Changing Screen Settings
````````````````````````
Tools Plus automatically recognizes when the user changes monitor settings via the “Monitors” Control Panel (in any version of the System). This includes [1] changing the orientation of multiple monitors in the “Monitors” Control Panel, [2] changing a monitor between color, gray-scale, or black and white, and [3] changing the number of colors or shades of gray that the monitor will display. Internally, a call to NumberOfScreens detects the change and recalculates the logical screen table. A doRefresh event is then generated, informing your application that all windows need to be redrawn incorporating the new settings.
Note: When your application is running in the THINK C or THINK Pascal
development environment, it will likely not detect the changes in
screen settings when the “Monitors” Control Panel is used.
Determine if the Macintosh running your application has Color QuickDraw.
pascal Boolean HasColorQuickDraw(void);
function HasColorQuickDraw: BOOLEAN;
HasColorQuickDraw informs your application if the Macintosh on which it is running has Color QuickDraw, and Tools Plus makes use of it. If your application has elected not to take advantage of Color QuickDraw (as specified when calling the InitToolsPlus routine at initialization), or if Color QuickDraw is not available, HasColorQuickDraw returns false.
Color drawing routines can only be used if the Mac has Color QuickDraw, so your application should not call any of the Macintosh toolbox’s color routines unless Color QuickDraw is present. Tools Plus takes care of handling its own drawing routines.
Determine the number of logical screens available on the Macintosh running your application.
pascal short NumberOfScreens(void);
function NumberOfScreens: INTEGER;
NumberOfScreens reports the number of logical screens (not physical monitors) that use unique color settings. Internally, this routine maintains a logical screen table that has one entry for each monitor with unique color or gray-scale settings. If three monitors are available, two having 256 colors and the third with 16 shades of gray, the logical screen table will contain two entries: the first being comprised of the combined region of the two 256 color monitors, and the second being the gray-scale monitor.
Use NumberOfScreens to determine the number of times a window’s color-dependent contents have to be drawn (once for each logical screen).
If the Macintosh running your application doesn’t have Color QuickDraw, or if color drawing has been disabled by the InitToolsPlus routine, NumberOfScreens returns a value of 1.
NumberOfScreens is optimized to rebuild the internal tables only if the user changes monitor settings via the “Monitors” control panel.
Begin updating the portion of the current window that is on the specified logical screen.
pascal void BeginUpdateScreen (short TheScreen);
procedure BeginUpdateScreen(TheScreen: INTEGER);
TheScreen specifies the logical screen number on which the drawing will occur. This number must be between 1 and the value returned by the NumberOfScreens routine.
Call BeginUpdateScreen just before you begin drawing the current window’s color-dependent contents. BeginUpdateScreen temporarily stores a copy of the current window’s visible region (visRgn) and replaces it with an intersection of the window’s visible region and the specified logical screen. This limits drawing to the area of the window that is visible only on the specified logical screen.
Subsequent calls to the ScreenDepth and ScreenHasColors routines will refer to the logical screen specified by theScreen.
Each call to BeginUpdateScreen must be balanced by a call to EndUpdateScreen. Also, BeginUpdateScreen and EndUpdateScreen cannot be nested (that is, you must call EndUpdateScreen before the next call to BeginUpdateScreen).
If the Macintosh running your application doesn’t have Color QuickDraw, or if color drawing has been disabled by the InitToolsPlus routine, or if theScreen is not a valid logical screen number, BeginUpdateScreen does nothing.
End updating the portion of the current window that is on the specified logical screen.
pascal void EndUpdateScreen(void);
procedure EndUpdateScreen;
Call EndUpdateScreen after you have completed drawing a window’s color-dependent contents. It restores the window’s visible region (visRgn) to its original value, that being prior to being altered by BeginUpdateScreen.
Each call to BeginUpdateScreen must be balanced by a call to EndUpdateScreen. Also, BeginUpdateScreen and EndUpdateScreen cannot be nested (that is, you must call EndUpdateScreen before the next call to BeginUpdateScreen).
If BeginUpdateScreen did not successfully modify the current window’s visible region, EndUpdateScreen does nothing.
Determine the number of colors (or shades of gray) available on the current logical screen.
pascal short ScreenDepth(void);
function ScreenDepth: INTEGER;
The ScreenDepth routine reports the current logical screen’s depth (in bits) as set by the “Monitors” control panel. Its value determines the number of colors (or shades of gray) that are seen on the logical screen. ScreenDepth is useful for optimizing programs to take advantage of whatever color capability a monitor has. The table below shows the number of colors that are available per ScreenDepth value.
ScreenDepth Colors/Grays
Value Available
``````````` ````````````
1 black & white
2 4
4 16
8 256
16 thousands
24 millions
32 millions+
ScreenDepth returns a valid value only if it is situated between calls to BeginUpdateScreen and EndUpdateScreen, since BeginUpdateScreen sets the current logical screen number. If ScreenDepth is called outside a BeginUpdateScreen / EndUpdateScreen structure, it reports on the main screen (the one containing the menu bar).
If the Macintosh running your application doesn’t have Color QuickDraw, or if color drawing has been disabled by the InitToolsPlus routine, or if BeginUpdateScreen did not successfully modify the current window’s visible region, ScreenDepth returns a value of 1.
Determine if a screen is set to draw in color (not gray-scale or black & white).
pascal Boolean ScreenHasColors(void);
function ScreenHasColors: BOOLEAN;
ScreenHasColors returns true if the current logical screen has been set by the “Monitors” control panel to display in color, and if Tools Plus has been initialized to make use of color via the InitToolsPlus routine. Use ScreenHasColors if you want to determine if a multi-bit screen is color or gray-scale.
ScreenHasColors returns a valid value only if it is situated between calls to BeginUpdateScreen and EndUpdateScreen, since BeginUpdateScreen sets the current logical screen number. If ScreenHasColors is called outside a BeginUpdateScreen / EndUpdateScreen structure, it reports on the main screen (the one containing the menu bar).
If the Macintosh running your application doesn’t have Color QuickDraw, or if color drawing has been disabled by the InitToolsPlus routine, or if BeginUpdateScreen did not successfully modify the current window’s visible region, ScreenHasColors returns false.
Reset the current window’s pen to the default values.
pascal void PenColorNormal(void);
procedure PenColorNormal;
PenColorNormal is a color equivalent of QuickDraw’s PenNormal procedure in that it resets the pen to its initial state (1x1 size, patCopy mode, black pattern). Additionally, if the Macintosh running your application has Color QuickDraw, and if color drawing has been enabled by the InitToolsPlus routine, the foreground color is set to black and the background color is set to white.
You can use the PenColorNormal procedure in place of PenNormal throughout your application, regardless if Color QuickDraw is available or used.
GetColorPenState is a color equivalent of QuickDraw’s GetPenState procedure in that it obtains a copy of the current window’s pen location, size, pattern, and display mode in ThePenState. Additionally, if the Macintosh running your application has Color QuickDraw, and if color drawing has been enabled by the InitToolsPlus routine, the foreground and background color are also stored in ThePenState. These settings can be restored later with SetColorPenState.
This routine is useful when calling subroutines that operate in the current window but must change the graphics pen. Each such procedure can save the pen’s state, perform whatever tasks it needs to do, then restore the original pen state immediately before returning. The ColorPenState record is defined as such:
ColorPenState = record {Color equivalent for a 'PenState' record}
You can use the GetColorPenState procedure in place of GetPenState throughout your application, regardless if Color QuickDraw is available, or if it is used (as specified when calling InitToolsPlus).
SetColorPenState is a color equivalent of QuickDraw’s SetPenState procedure in that it sets the current window’s pen location, size, pattern, and display mode according to the values stored in ThePenState. Additionally, if the Macintosh running your application has Color QuickDraw, and if color drawing has been enabled by the InitToolsPlus routine, the foreground and background colors are also set.
This is usually done at the end of a procedure that has altered the pen parameters and wants to restore them to their original state that existed at the beginning of the procedure. (See GetColorPenState.)
You can use the SetColorPenState procedure in place of SetPenState throughout your application, regardless if Color QuickDraw is available, or if it is used (as specified when calling InitToolsPlus).
